## Status: WIP — chip init succeeds, RX data flow still silent

Brings up the RTL8821AU end-to-end except for RX bulk-IN data flow.
Posting so @RomanLut and others can continue the investigation from a
clean checkpoint that builds against current master instead of
resurrecting #22 (which deletes the 8814AU work and has a parallel
dispatch enum that doesn't compose with the `ICType`-based convention
#23-#29 established).

## What works on T2U Plus 2357:0120 (verified on macOS)

- Chip detection: `CHIP_8821_Normal_Chip_TSMC_D_CUT_1T1R`
- 8821 power-on flow (`rtl8821A_card_enable_flow`)
- Firmware download — 8821 blob, signature `0x2101`, FW ready in ~30ms
- MAC/BB/AGC/RadioA register tables via existing `PhyTableLoader` (same
phydm conditional encoding as 8814AU)
- RFE pinmux (`phy_SetRFEReg8821`), band switch 2.4G/5G, channel + TX
power table on ch6/36/100
- USB endpoint discovery: bulk IN 0x84, OUTs 0x05/0x06/0x08/0x09 (vs
8812/8814's 0x81 and 0x02-0x05)
- `libusb_clear_halt` on IN + `REG_USB_HRPWM=0x84` LPS wake

## What's NOT working

- **RX bulk-IN reads succeed at the USB layer but the chip never pushes
data.** 0 RX packets across 15s on ch100 even with the host Mac actively
associated to a busy 5GHz AP. The chip-internal RX-DMA → bulk-IN-EP
binding isn't engaging despite all known init steps.
- TX path is wired (correct OUT EP, no `LIBUSB_ERROR_NOT_FOUND`) but
unvalidated end-to-end on 8821AU — no peer sniffer in this session.

## Regression matrix (Linux trainer-arch, master vs
`feat/rtl8821au-support`)

| Adapter | Test | Result | vs master |
|---|---|---|---|
| 8812AU (`0bda:8812`) | RX | 41 pkts / 15s, 0 errors, `CHIP_8812`
detected | ✓ no regression |
| 8812AU | TX | 15 prints all `rc=1`, 0 failures (2 runs) | ✓ no
regression |
| 8814AU (`0bda:8813`) | RX | 0 pkts | ✓ matches master baseline
(pre-existing) |
| 8814AU | TX | `rc=1`, ~270-320 async failures (timing-variant) | ✓
matches master baseline |

The new `CHIP_8821` dispatch correctly routes 8812 → 8812 path and 8814
→ 8814 path. No misrouting.

## Suggested next steps for whoever picks this up

1. usbmon trace of `aircrack-ng/rtl8812au`'s RX bring-up against an
8821AU on Linux; diff post-fwdl register writes vs ours
(REG_TRXDMA_CTRL, REG_USB_AGG_TH/TO, REG_RXDMA_AGG_PG_TH,
REG_USB_SPECIAL_OPTION).
2. Compare register state post-init (kernel-driver readback vs our
post-init pyusb dump). Same technique that unblocked the 8814AU TX work.
3. Re-read @RomanLut's #22 `HalModule.cpp` for any 8821-specific init
steps I didn't carry over when rewiring through `ICType`.

## What this preserves

- 8812AU support — untouched (default dispatch branch)
- 8814AU support — untouched (#23-#29 work preserved)
- Same `HAL_IC_TYPE_E` / `ICType` dispatch pattern; no parallel enum

## Attribution

8821a HAL data (`Hal8821APwrSeq`, `Hal8821PhyReg`, `hal8821a_fw`) ported
verbatim from @RomanLut's #22 (svpcom/rtl8812au v5.2.20). Wiring re-done
to follow master's existing convention.

Refs #20 (BadPotato1007's underlying request) and #22 (RomanLut's
original port).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: RomanLut <noreply@github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## What this is

A manual-run Python orchestrator that compares devourer's userspace
stack against the kernel driver (mainline `rtw88` / out-of-tree
`aircrack-ng/rtl8812au`) on a host with two plugged-in USB Wi-Fi
adapters. Emits a markdown table — designed to paste into PR review
comments.

```
                  TX = devourer        TX = kernel
RX = devourer     [end-to-end dvr]     [does dvr RX a kernel-TX frame?]
RX = kernel       [does dvr emit       [baseline / rig sanity]
                   valid frames?]
```

Each cell injects/receives the canonical beacon (SA `57:42:75:05:d6:00`,
matching `txdemo/main.cpp`) for `--duration` seconds and counts hits.

## Why now

PRs like #30 (RTL8821AU partial bring-up) need cross-driver validation:
\"does devourer's TX really emit valid frames?\" and \"can devourer RX a
frame the kernel driver knows works?\". Running these checks manually is
fiddly (modprobe / unbind / iw / tcpdump dance per cell); this script
does it in one command and prints a structured result.

This is **not** a 24x7 CI runner — too few PRs to justify the
infrastructure. It's a script the reviewer runs on demand on a test rig.

## Usage

```bash
cd /path/to/devourer && cmake --build build -j
sudo python3 tests/regress.py --channel 100
```

See [`tests/README.md`](tests/README.md) for full options + prereqs.

## First-run validation on trainer-arch

Arch Linux, kernel 6.x, USB hub with 0bda:8812 (8812AU) + 0bda:8813
(8814AU):

```
## Regression matrix — channel 100
- TX adapter: 0bda:8813 (RTL8814AU)
- RX adapter: 0bda:8812 (RTL8812AU)

|   | TX = devourer | TX = kernel |
|---|---|---|
| RX = devourer | 0 hits / 10 TX (437 fail) / 10s ✗ | 0 hits / 0 TX / 0s ✗ |
| RX = kernel | 1 hits / 10 TX (351 fail) / 10s ✓ | 0 hits / 0 TX / 0s ✗ |
```

The **devourer-TX(8814) → kernel-RX(8812) cell passed** — independent
confirmation that #29's 8814AU TX bring-up really does land frames on
the air. The remaining cells correctly identified the rig's known
limitations: mainline `rtw88_8814au` can't probe this 8814AU dongle on
this kernel (`failed to download firmware`, probe error -22), and 8814AU
RX is a pre-existing TODO.

## Portability

- Tool paths resolved via `which` (no `/usr/bin/X` hardcoding)
- Wlan iface names discovered via `iw dev` (works for systemd `wlp*` and
classic `wlan*`)
- Kernel driver claiming each DUT read from sysfs (no hardcoded module
names)
- Preflight check prints distro-agnostic install hints if anything's
missing
- Tested on Arch; should work on any modern Linux with `iw`, `tcpdump`,
`python3-scapy`, `aircrack-ng`

## VM-readiness

The kernel-cell shell-outs all go through one function
(`run_kernel_cmd`). Today: local exec. To migrate the kernel driver into
a pinned-kernel VM (recommended once host kernel upgrades start breaking
the out-of-tree aircrack-ng driver), wrap that function with `ssh
trainer-vm sudo` and arrange USB hot-plug passthrough via libvirt. The
matrix orchestrator doesn't need to change.

## Known limitations (documented in README)

- Tests \"signal of life\", not throughput — air noise makes absolute
counts unreliable; default pass-threshold is 1 hit with guidance to bump
for higher-confidence runs.
- Sequential matrix takes ~100s for 4 cells (devourer fwdl warmup + 4 ×
~25s).
- Two-adapter scope today. Extending to >2 is a pairing loop in
`main()`.
- One known bug: `<devourer-tx>TX #N` prints are rate-limited so when
the chip is failing every send, the parser undercounts attempts.
Mitigated by surfacing failure count separately in the output.

## Test plan

- [x] Builds + runs on trainer-arch (Arch + kernel 6.x)
- [x] Markdown table emitted correctly
- [x] At least one cell passes against real hardware (8814 dvr-TX → 8812
kernel-RX)
- [ ] Validate on a different distro (Ubuntu / Fedora) — anyone with a
2-adapter rig
- [ ] Validate against the out-of-tree `aircrack-ng/rtl8812au` driver
instead of mainline rtw88

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>